home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / c / dice-3.16.lha / doc / amiga.doc < prev    next >
Text File  |  1993-07-06  |  20KB  |  829 lines
  1.  
  2.     AMIGA.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/amiga/alloca.a
  7. c.lib/amiga/c.a
  8. c.lib/amiga/chkabort
  9. c.lib/amiga/_divs
  10. c.lib/amiga/_divu
  11. c.lib/amiga/exec_dcc
  12. c.lib/amiga/_ExecSeg
  13. c.lib/amiga/exit
  14. c.lib/amiga/main
  15. c.lib/amiga/onbreak
  16. c.lib/amiga/_mods
  17. c.lib/amiga/_modu
  18. c.lib/amiga/_muls
  19. c.lib/amiga/_mulu
  20. c.lib/amiga/_SearchPath
  21. c.lib/amiga/_SearchResident
  22. c.lib/amiga/stack_abort
  23. c.lib/amiga/wbmain
  24. c.lib/amiga/x.a
  25. c.lib/amiga/rega4
  26.  
  27.  
  28. amiga/alloca                        amiga/alloca
  29.  
  30.    NAME
  31.     alloca - allocate memory from the stack
  32.  
  33.    SYNOPSIS
  34.     void *ptr = alloca(long bytes);
  35.  
  36.    FUNCTION
  37.     alloca() comes from the UNIX world.  It allocates memory off the
  38.     stack for use within a procedure.  The allocated memory is
  39.     automatically freed when the subroutine returns.
  40.  
  41.     DO NOT USE ALLOCA() IF YOU CAN HELP IT.  alloca() is not easily
  42.     portable across machines.
  43.  
  44.    NOTE
  45.     When a low stack condition arises, alloca() will abort by printing
  46.     an error message and calling abort();  alloca() does NOT currently
  47.     try to allocate dynamic memory when it runs out of stack.
  48.  
  49.     Some implementations of alloca() use alloca(0) to free allocated
  50.     stack.    This feature is NOT currently implemented in DICE's
  51.     alloca() call.
  52.  
  53.    EXAMPLE
  54.     #include <alloca.h>
  55.     #include <stdio.h>
  56.  
  57.     main(ac, av)
  58.     char *av[];
  59.     {
  60.         char *ptr;
  61.         if (ac == 1) {
  62.         puts("test string");
  63.         exit(1);
  64.         }
  65.         ptr = alloca(strlen(av[1]) + 8);
  66.         sprintf(ptr, "FOO.%s", av[1]);
  67.         puts(ptr);
  68.         return(0);
  69.     }
  70.  
  71.    SEE ALSO
  72.     setjmp(), longjmp()
  73.  
  74.  
  75.  
  76. amiga/c.a                        amiga/c.a
  77.  
  78.    NAME
  79.     c.a  - DICE startup module for all C programs
  80.  
  81.    SYNOPSIS
  82.     c.a is entered when the program segment is run
  83.  
  84.    FUNCTION
  85.     DCC specifies DLIB:C.O first when linking objects into an
  86.     executable.  C.O also exists in C.LIB but is not normally pulled
  87.     since it is already included in the link line.
  88.  
  89.     C.O does the following:
  90.  
  91.         (1) save non-scratch registers
  92.  
  93.         (2) If Resident:
  94.             Allocate space for both data & bss and copy the
  95.             initialized data into the allocated space.    Clear
  96.             the BSS portion of the data space
  97.         Else
  98.             The BSS has already been allocated by the load module
  99.             but not cleared, Clear the BSS portion of the data space
  100.  
  101.         (3) Clear the ^C signal
  102.  
  103.         (4) Setup _SysBase
  104.  
  105.         (5) Call all AUTOINIT subroutines (this usually results in at
  106.         least the dos.library being openned).
  107.  
  108.         (6) call _main()    (usually in c.lib as well)
  109.  
  110.         (7) fall through to _exit(0)
  111.  
  112.     Note that while c.a falls through to _exit(0) after calling _main(),
  113.     _main itself calls main() with: exit(main(args...));  Thus, main()
  114.     is always expected to return a valid value (i.e. not void).
  115.  
  116.     C.O also handles the low level exit _exit() (__exit:) in the
  117.     following sequence:
  118.  
  119.         (1) Call autoinit exit subroutines (this normally closes the
  120.         DOS library and other automatically openned libraries such
  121.         as floating point libraries).
  122.  
  123.         (2) Free all memory allocated by the task, including the small
  124.         data segment & BSS space.  Note that all variables that we
  125.         use after this have already been placed in registers since
  126.         the dataspace is no longer valid.
  127.  
  128.         (3) If the _WBMsg is not NULL then:
  129.         (a) Forbid()
  130.         (b) ReplyMsg(_WBMsg)
  131.  
  132.         (4) restore original registers and rts (exit out of the process)
  133.  
  134.  
  135.    NOTE
  136.     Normally the programmer does not overide the startup object file
  137.     (c.o) since this is the entry point into the program.  However, in
  138.     many cases a programmer will want to overide _main().  I.E.:
  139.  
  140.     _main(len, arg)
  141.     int len;
  142.     char *arg;
  143.     {
  144.         ...
  145.     }
  146.  
  147.     In which case he is given the length and arg pointer passed to the
  148.     program on startup.  When you overide _main() you cannot call any
  149.     stdio (fopen, fclose, puts, etc...), low level IO (open, close,
  150.     read, write, etc...), or memory allocation routines.
  151.  
  152.     Normally _main will be overriden if the program makes only system
  153.     calls (such as Open, Close, Read, Write, FindTask, etc...).
  154.     Overriding the c.lib generally makes executables much smaller as no
  155.     extranious stdio/low level IO routines are brought in from c.lib .
  156.  
  157.     Normally you exit out of _main by calling _exit(code) (note the
  158.     underscore).
  159.  
  160.    SEE ALSO
  161.  
  162.  
  163. amiga/chkabort                        amiga/chkabort
  164.  
  165.    NAME
  166.     chkabort - check for ^C and take the appropriate action
  167.  
  168.    SYNOPSIS
  169.     (void) chkabort(void);
  170.  
  171.    FUNCTION
  172.     Checks for a ^C and takes the appropriate action.  If the appropriate
  173.     action is to exit than this routine does not return.  stdio and other
  174.     routines will call chkabort() at various points.
  175.  
  176.     The action taken by ^C may be set by the signal() or onbreak() calls.
  177.  
  178.    EXAMPLE
  179.     /*
  180.      *  wait for somebody to hit ^C (note that this is very wasteful of
  181.      *  CPU and thus isn't a real good example).
  182.      */
  183.  
  184.     main()
  185.     {
  186.         int i;
  187.  
  188.         for (i = 0; i < 10000000; ++i)
  189.         chkabort();
  190.         return(0);
  191.     }
  192.  
  193.    SEE ALSO
  194.     onbreak, atexit, signal
  195.  
  196.  
  197. amiga/_divs                        amiga/_divs
  198.  
  199.    NAME
  200.     _divs - signed long divide 32/32->32 assembly tag
  201.         not callable from C
  202.  
  203.    ENTRY
  204.     D0 = 32 bit signed integer
  205.     D1 = 32 bit signed integer
  206.  
  207.    RETURN
  208.     D0 = D0 / D1
  209.  
  210.    FUNCTION
  211.     This is an assembly function that DICE uses whenever it needs to
  212.     do a long division.  This function is not callable from C.
  213.  
  214.    SEE ALSO
  215.     _divu, _mods, _modu, _muls, _mulu
  216.  
  217.  
  218. amiga/_divu                        amiga/_divu
  219.  
  220.    NAME
  221.     _divu - unsigned long divide 32/32->32 assembly tag
  222.         not callable from C
  223.  
  224.    ENTRY
  225.     D0 = 32 bit unsigned integer
  226.     D1 = 32 bit unsigned integer
  227.  
  228.    RETURN
  229.     D0 = D0 / D1
  230.  
  231.    FUNCTION
  232.     This is an assembly function that DICE uses whenever it needs to do
  233.     an unsigned long division.  This function is not callable from C.
  234.  
  235.    SEE ALSO
  236.     _divs, _mods, _modu, _muls, _mulu
  237.  
  238.  
  239.  
  240. amiga/exec_dcc                        amiga/exec_dcc
  241.  
  242.    NAME
  243.     exec_dcc - call DICE executable
  244.  
  245.    FUNCTION
  246.     DO NOT EVER USE THIS FUNCTION.    This is an internal DICE function
  247.     used by DCC and is subject to change without notice.  This function
  248.     can easily break under new versions of the OS and special care is
  249.     taken by DCC when using it.
  250.  
  251.     The 2.0 version of the Amiga operating system has calls that will
  252.     properly accomplish this operation.
  253.  
  254.    SEE ALSO
  255.     _ExecSeg
  256.  
  257.  
  258. amiga/_ExecSeg                        amiga/_ExecSeg
  259.  
  260.    NAME
  261.     _ExecSeg - call a segment
  262.  
  263.    FUNCTION
  264.     DO NOT EVER USE THIS FUNCTION.    This is an internal DICE function
  265.     used by DCC and is subject to change without notice.  This function
  266.     can easily break under new versions of the OS and special care is
  267.     taken by DCC when using it.
  268.  
  269.     The 2.0 version of the Amiga operating system has calls that will
  270.     properly accomplish this operation.
  271.  
  272.    SEE ALSO
  273.     exec_dcc
  274.  
  275.  
  276. amiga/exit                        amiga/exit
  277.  
  278.    NAME
  279.     exit - exit from a program 'nicely'
  280.  
  281.    SYNOPSIS
  282.     (void) exit(code)
  283.  
  284.    FUNCTION
  285.     exits the program and returns the specified exit code.    Normally you
  286.     pass 0 to indicate no errors, a positive number to indicate a program
  287.     error to the parent.
  288.  
  289.     exit() closes all stdio file pointers, low level file descriptors,
  290.     perhaps other things, then finally calls _exit with the code.
  291.  
  292.     If you use main() you should call exit() to exit the program or
  293.     return an error code from main.  If you use the _main() entry
  294.     point (only for programmers dead set on optimizing executable
  295.     size and using only system library calls) you should use the _exit()
  296.     exit point.
  297.  
  298.    EXAMPLE
  299.     main(ac, av)
  300.     char *av[];
  301.     {
  302.         if (ac <= 1) {
  303.         puts("I expected an argument you idiot!");
  304.         exit(1);
  305.         }
  306.         puts("thanks for the argument!");
  307.         exit(0);
  308.     }
  309.  
  310.    SEE ALSO
  311.     main, _main, _exit
  312.  
  313.  
  314. amiga/_exit                         amiga/_exit
  315.  
  316.    NAME
  317.     _exit - exit from a program without bother to release resources
  318.  
  319.    SYNOPSIS
  320.     (void) _exit(code)
  321.     int code;
  322.  
  323.    FUNCTION
  324.     exits the program and returns the specified exit code.    Normally you
  325.     pass 0 to indicate no errors, a positive number to indicate a program
  326.     error to the parent.  Note that since auto-init openned libraries
  327.     are closed in the startup module (c.o), automatically openned
  328.     libraries WILL be automatically closed for you.  However, any
  329.     libraries you manually declare the library base variable for and
  330.     manually open must be closed by you.
  331.  
  332.     You should only call _exit() if you used the _main() entry point
  333.     (instead of the usual main()), and then only